home *** CD-ROM | disk | FTP | other *** search
/ The Pier Shareware 1 / Pier Shareware 1.iso / gap / gap_list.doc next >
Text File  |  1992-10-10  |  39KB  |  911 lines
  1.  
  2.           
  3.  
  4.  
  5.           
  6.                   GAP_LIST - The External File Lister for GAP
  7.           
  8.           Copyright (c) 1992 RoboSoft Systems. All Rights Reserved.
  9.           
  10.           
  11.           GAP_LIST is an external program used to generate file
  12.           listings for GAP BBSs.  It will allow you to easily and
  13.           quickly create file listings while you wait or in an event.
  14.           
  15.           Why do you need a program such as this when GAPFILE can
  16.           already produce file listings?  Well, to start with,
  17.           GAP_LIST was created with just one purpose in mind -- to
  18.           create file lists.  It has been highly optimized for this
  19.           specific mission.  GAP_LIST also generates all of the
  20.           requested listings with just a single pass through the
  21.           database.  What this adds up to is speed and flexibility.
  22.           On my system I can generate condensed and enhanced listings
  23.           for the main board in about half the time it takes to do
  24.           just a condensed listing with GAPFILE.
  25.           
  26.           GAP_LIST also lets you create listings for individual file
  27.           directories (registered version only).  If your master lists
  28.           are anywhere near as big as mine, this can really help out
  29.           your users who don't want to spend an hour or more
  30.           downloading your whole file listing just to get the couple
  31.           subjects they're interested in.
  32.           
  33.           GAP_LIST can create "raw" listings for use with transfer
  34.           protocols that can check uploads for duplicates.  (HS/Link
  35.           has this capability.)  GAP_LIST can also create color
  36.           bulletins showing how many files and bytes you have in each
  37.           subject, with totals for each area.
  38.           
  39.           Finally, GAP_LIST will do all this right from the command
  40.           line using a configuration file you've set up ahead of time.
  41.           This means you can generate individual file lists for any or
  42.           all of your forums in a nightly event, and have the listings
  43.           separated almost any way you'd like.  (GAPFILE can generate
  44.           listings from the command line, but can only do a single
  45.           type of listing without manual intervention.)
  46.           
  47.           GAP_LIST comes in two versions, one for single-node boards
  48.           and one for multi-node boards.  (The multi-node version is
  49.           available to registered users only.) You can use the
  50.           single-node version on multi-node boards, but you must be
  51.           sure that all nodes are inactive before running GAP_LIST.
  52.           The multi-node version allows you to generate file listings
  53.           while users are online and can be easily set up to run from
  54.           an event.
  55.           
  56.           
  57.           Disclaimer
  58.           ----------
  59.           
  60.           GAP_LIST is provided AS IS without any warranty, expressed
  61.           or implied, including, but not limited to, fitness for any
  62.           purpose.  Use of GAP_LIST, and the consequences thereof, are
  63.  
  64.  
  65.                                      Page 1                           
  66.  
  67.           GAP_LIST v1.1                                       10/10/92
  68.  
  69.  
  70.           entirely your risk.  In no event will RoboSoft Systems be
  71.           liable for any damages whatsoever resulting from the use of
  72.           GAP_LIST.
  73.           
  74.           
  75.           Shareware
  76.           ---------
  77.           
  78.           GAP_LIST is a Shareware product.  As such, it is made
  79.           available to the GAP sysop community for evaluation.  Users
  80.           are licensed to operate this program on their computers for
  81.           the purpose of test and evaluation on a trial basis for 30
  82.           days.  If GAP_LIST is used after the first 30 days,
  83.           registration with RoboSoft Systems is required.
  84.           
  85.           Registration
  86.           ------------
  87.           
  88.           Registered users are those users who elect to pay for
  89.           GAP_LIST and register that payment with RoboSoft Systems.
  90.           By virtue of registration and payment for the program,
  91.           registered users are granted a license to continue to
  92.           utilize the program on their personal computer for as long
  93.           as they choose.  This license authorizes use of the program 
  94.           on any personal computer system the user may own or use so 
  95.           long as the program is operated on only one computer system 
  96.           at a time.  Use on multiple systems simultaneously requires 
  97.           multiple registrations.
  98.           
  99.           The registration fee for GAP_LIST is $15.  Please make
  100.           checks payable to:
  101.           
  102.                                 RoboSoft Systems
  103.                                  P.O. Box 2221
  104.                                 Orange, CA  92669
  105.           
  106.           The payment of this registration fee to RoboSoft Systems
  107.           entitles the user to full use of GAP_LIST for an unlimited
  108.           period of time.  Registered users will receive a disk with 
  109.           both single- and multi-node versions of GAP_LIST, a 
  110.           registration key file that will unlock ALL the program 
  111.           features, and some complementary support programs.
  112.           
  113.           
  114.           Updates
  115.           -------
  116.           
  117.           Updates to GAP_LIST will be provided via BBS free of charge
  118.           to registered users.  Updates on diskette are available for
  119.           a nominal charge to cover materials and handling.
  120.           
  121.           
  122.           Support
  123.           -------
  124.           
  125.           Support for GAP_LIST is available on The Cookie Jar BBS at
  126.           714-997-0350.  Registered users will be granted access to
  127.           the private node of the BBS and will be given priority in
  128.  
  129.  
  130.                                      Page 2                           
  131.  
  132.           GAP_LIST v1.1                                       10/10/92
  133.  
  134.  
  135.           having their questions answered.
  136.           
  137.           Distribution
  138.           ------------
  139.           
  140.           GAP_LIST may be freely distributed on any Bulletin Board
  141.           System (BBS), including commercial systems such as
  142.           CompuServe (CIS), Genie, and BIX.  GAP_LIST may be
  143.           distributed by diskette by any organization or disk
  144.           distributor as long as the fee for this distribution is no
  145.           greater than $5 and it is made clear to the purchaser that
  146.           the distribution fee is NOT the same as the registration
  147.           fee.
  148.           
  149.           Feel free to pass around copies of GAP_LIST, however, please
  150.           distribute all of the original files and do not modify any
  151.           of the files.
  152.           
  153.           
  154.           
  155.           Enough with the BS, how do I use this thing?
  156.           --------------------------------------------
  157.           
  158.           The command-line syntax for GAP_LIST is very simple.  It
  159.           REQUIRES one parameter - the name of the controlling
  160.           configuration file.
  161.           
  162.               GAP_LIST <configuration filename>
  163.           
  164.           Example:
  165.           
  166.               GAP_LIST C:\GAP\GAP_LIST.PRM
  167.           
  168.           GAP_LIST will produce a listing of your GAP filebase
  169.           according to the specifications you provide in the
  170.           configuration file.  This is where things get just a bit
  171.           trickier.  GAP_LIST understands some very simple commands
  172.           that tell it which AREA/SUBJECT(s) to create listings for,
  173.           which listings to create, and where to put them.
  174.           
  175.           There are several commands recognized by GAP_LIST: MAIN,
  176.           SEPARATOR, PRIVATE, MASTER, IGNORE, AREA, and SUBJECT.  The
  177.           MAIN command tells GAP_LIST where your GAP\MAIN directory
  178.           is.  The SEPARATOR command is used to indicate how you want
  179.           individual file entries in the enhanced listings separated
  180.           -- with blank space or with a printable separator line.  The
  181.           PRIVATE command specifies the security level of private
  182.           files you don't want printed in the listings.  The MASTER
  183.           command is used to specify the names of master files that
  184.           will contain listings for every area and subject covered
  185.           during this run of GAP_LIST.  The IGNORE command is used to
  186.           indicate any files to be excluded from the new file scan.
  187.           The AREA command is used to indicate which forums you want
  188.           included in the listings and what listings you want
  189.           generated for that forum.  The SUBJECT command gives you
  190.           control down to the individual subject over which files are
  191.           listed.
  192.           
  193.  
  194.  
  195.                                      Page 3                           
  196.  
  197.           GAP_LIST v1.1                                       10/10/92
  198.  
  199.  
  200.           Before we get into the details about each configuration
  201.           command, here's a brief sample configuration file for you to
  202.           refer to while reading the command descriptions.
  203.           
  204.              MAIN i:\gap\main
  205.              SEPARATOR -
  206.              PRIVATE 110
  207.              MASTER RAW files.lst BULLETIN blt11
  208.              IGNORE @list.xcl
  209.              AREA 0 GEN i:\gap\gen CONDENSED main.lst ENHANCED main.enh 
  210.                   TITLE "The Cookie Jar Main Board" 
  211.              SUBJECT CONDENSED dir%03i.lst
  212.              AREA 2 GEN i:\gap\windows\gen CONDENSED windows.lst 
  213.                   ENHANCED windows.enh 
  214.                   TITLE "The Cookie Jar Windows Forum"
  215.              AREA 3 GEN i:\gap\graphics\gen CONDENSED graphics.lst 
  216.                   ENHANCED graphics.enh 
  217.                   TITLE "The Cookie Jar Graphics Forum"
  218.              AREA 4 GEN i:\gap\program\gen CONDENSED program.lst 
  219.                   ENHANCED program.enh 
  220.                   TITLE "The Cookie Jar Programming Forum"
  221.           
  222.           (The indented lines in the above example are continuations
  223.           of the previous line.  Line wrapping of this sort is NOT
  224.           allowed in the actual configuration file.  We were forced to
  225.           do it here because of the line length limitations of this
  226.           document.)
  227.           
  228.           The MAIN Command
  229.           ----------------
  230.           
  231.           Command Format:   MAIN <GAP\MAIN directory path>
  232.           
  233.           The MAIN command is REQUIRED.  It specifies the path to your
  234.           GAP\MAIN directory.  It doesn't have to be the first thing
  235.           in the configuration file, but it MUST be present somewhere
  236.           in the file.
  237.           
  238.           
  239.           The SEPARATOR Command
  240.           ---------------------
  241.           
  242.           Command Format:   SEPARATOR [<separator character>]
  243.           
  244.           The SEPARATOR command (optional) specifies how GAP_LIST
  245.           should separate the individual file entries in the enhanced
  246.           listings.  The first non-blank character following the
  247.           SEPARATOR keyword is used to create a separator line.  The
  248.           command "SEPARATOR *" will cause a line of asterisks to be
  249.           printed between each entry in the enhanced listing.  If the
  250.           configuration file does not contain a SEPARATOR command, a
  251.           line of graphical single horizontal line characters is used.
  252.           Something like:
  253.           
  254.           ───────────────────────────────────────────────────────────
  255.           
  256.           If the SEPARATOR command is specified without a following
  257.           non-blank character, each entry in the enhanced listings
  258.  
  259.  
  260.                                      Page 4                           
  261.  
  262.           GAP_LIST v1.1                                       10/10/92
  263.  
  264.  
  265.           will be separated by two blank lines.  This behavior mimics
  266.           that of the enhanced listing created by the GAPFILE Master
  267.           Listing function.
  268.           
  269.           
  270.           The PRIVATE Command
  271.           -------------------
  272.           
  273.           Command Format:   PRIVATE <seclev>
  274.           
  275.           The PRIVATE command (optional) specifies the security level
  276.           of private files that should not be included in the
  277.           listings.  Any file with a security level greater than or
  278.           equal to the specified level will not be included in the
  279.           listings.  If the PRIVATE command is not used, a default
  280.           private level of 110 will be used.
  281.           
  282.           
  283.           The MASTER Command
  284.           ------------------
  285.           
  286.           Command Format:   MASTER [CONDENSED <filename>] 
  287.                                [ENHANCED <filename>] [RAW <filename>]
  288.                                [BULLETIN <filename>]
  289.           
  290.           The MASTER command (optional) is used to specify listing
  291.           files that will contain all files listed by GAP_LIST in all
  292.           AREAs and SUBJECTs.  The MASTER command accepts several
  293.           sub-commands.  All the sub-commands must be on the same line
  294.           as the MASTER command.  There is no limit to the length of
  295.           the line.  All the sub-commands and their associated
  296.           parameters must be separated by one or more spaces.
  297.           
  298.           You may have more than one MASTER command in your
  299.           configuration file, but only the last occurrence of any
  300.           sub-command will have effect.  For instance, if your
  301.           configuration file contained the following lines
  302.           
  303.                MASTER ENHANCED master.enh CONDENSED master.lst
  304.                MASTER ENHANCED main.enh
  305.           
  306.           the CONDENSED sub-command from the first MASTER command
  307.           would still be in effect, but the ENHANCED sub-command from
  308.           the second MASTER command will override the ENHANCED
  309.           sub-command in the first line.
  310.           
  311.           
  312.           
  313.           
  314.           CONDENSED Sub-Command (MASTER)
  315.           ------------------------------
  316.           
  317.           Sub-Command Format: CONDENSED <filename>
  318.           
  319.           This is an optional sub-command that indicates you want a
  320.           condensed (one line per file) listing of all AREAs and
  321.           SUBJECTs specified in the configuration file.  This is
  322.           essentially the same as specifying CONDENSED files for each
  323.  
  324.  
  325.                                      Page 5                           
  326.  
  327.           GAP_LIST v1.1                                       10/10/92
  328.  
  329.  
  330.           AREA and then pasting all those files together.  <filename>
  331.           indicates where you want the listing to go.  <filename> may
  332.           be a relative (..\all.lst) or absolute
  333.           (c:\gap\filelist\all.lst) file specification.  You must
  334.           specify a filename following the CONDENSED sub-command.
  335.           
  336.           Example:  MASTER CONDENSED c:\gap\filelist\all.lst
  337.           
  338.           
  339.           ENHANCED Sub-Command (MASTER) 
  340.           -----------------------------
  341.                                                   
  342.           Sub-Command Format:  ENHANCED <filename>
  343.           
  344.           This is an optional sub-command that indicates you want an
  345.           enhanced (complete file information) listing of all AREAs
  346.           and SUBJECTs specified in the configuration file.
  347.           <filename> indicates where you want the listing to go.
  348.           <filename> may be a relative or absolute file specification.
  349.           You must specify a filename following the ENHANCED
  350.           sub-command.
  351.           
  352.           Example: MASTER ENHANCED c:\gap\filelist\all.enh
  353.           
  354.           
  355.           RAW Sub-Command (MASTER)
  356.           ------------------------
  357.           
  358.           Sub-Command Format:  RAW <filename>
  359.           
  360.           This is an optional sub-command that indicates you want a
  361.           raw listing of all the filenames in the AREAs and SUBJECTs
  362.           specified in the configuration file.  This is primarily for
  363.           use with protocols like HS/Link that can use such a file to
  364.           check for duplicates prior to accepting uploads.  <filename>
  365.           indicates where you want to listing to go.  <filename> may
  366.           be a relative or absolute file specification.  You must
  367.           specify a filename following the RAW sub-command.
  368.           
  369.           Note for those running a multi-node setup: If any of your
  370.           nodes are online while you're running GAP_LIST, be sure to
  371.           have GAP_LIST use a temporary file for the RAW listing and
  372.           then copy this temporary over the file normally accessed by
  373.           HS/Link.  If you send the RAW listing output to the same
  374.           file used by HS/Link to check for duplicates, you'll get a
  375.           sharing violation if someone uploads with HS/Link while
  376.           you're running GAP_LIST.
  377.           
  378.           The RAW sub-command can also be used with the AREA and
  379.           SUBJECT commands, but it will be most useful with the MASTER
  380.           command.
  381.           
  382.           
  383.           BULLETIN Sub-Command (MASTER) 
  384.           -----------------------------
  385.                                                   
  386.           Sub-Command Format:  BULLETIN <filename>
  387.           
  388.  
  389.  
  390.                                      Page 6                           
  391.  
  392.           GAP_LIST v1.1                                       10/10/92
  393.  
  394.  
  395.           This is an optional sub-command that indicates you want
  396.           GAP_LIST to create a summary bulletin listing the total
  397.           number of files and bytes in each AREA and SUBJECT specified
  398.           in the configuration file.  The bulletin file is formatted
  399.           to 80 columns and uses ANSI color.  A grand total of all
  400.           files listed is printed at the very bottom of the bulletin.
  401.           The total bytes is tracked and listed in K-bytes since it's
  402.           possible that some boards may have extremely large
  403.           filebases.
  404.           
  405.           Example: MASTER BULLETIN c:\gap\gen\blt12
  406.           
  407.           
  408.           The IGNORE Command
  409.           -------------------
  410.           
  411.           The IGNORE command (recognized by registered version only)
  412.           is used to specify any files that should not be considered
  413.           when determining the newest file in an area or subject.  To
  414.           provide maximum execution speed, GAP_LIST will only generate
  415.           a listing for an area or subject if there are new files
  416.           present in that area or subject.  (The demo version does not
  417.           include this feature.  It will generate listings for all
  418.           requested areas/subjects whether there are new files or
  419.           not.) It compares the date of the existing listing file (if
  420.           one does exist) to the date of the most recent file in the
  421.           area/subject in question.  If the listing file was generated
  422.           after the date of the most recent file, a new listing will
  423.           not be generated.  This prevents GAP_LIST from reproducing
  424.           the same listing over and over for an area/subject that has
  425.           had no uploads.
  426.           
  427.           The only catch is that if you update the filebase everytime
  428.           you run GAP_LIST, you'll always have at least one new file
  429.           (the newly generated listing file) the next time you run
  430.           GAP_LIST.  By using the IGNORE command, you can tell
  431.           GAP_LIST to ignore your listing files when determining the
  432.           date of the newest file in an area/subject.  So if the
  433.           listing file is the only new file in an area, a listing for
  434.           that area will not be generated.
  435.           
  436.           The IGNORE command is interpreted slightly differently
  437.           depending on where it occurs in the configuration file.  An
  438.           IGNORE command that occurs before the first AREA command
  439.           defines a list of files that will be ignored for the entire
  440.           filebase.  An IGNORE command that occurs after an AREA
  441.           command defines a list of files that will be ignored only for
  442.           the area defined by the preceeding AREA command.
  443.           
  444.           Command Format:   IGNORE [@<filelist>] [<filename>]
  445.           
  446.           The IGNORE command will accept any number of filenames.  If
  447.           a filename is preceeded by a @, that filename will be
  448.           assumed to contain a list of filenames to be ignored, one
  449.           name per line.  Any number of IGNORE commands can be
  450.           specified in the configuration file.
  451.           
  452.           Note, the IGNORE command is used only when determining the
  453.  
  454.  
  455.                                      Page 7                           
  456.  
  457.           GAP_LIST v1.1                                       10/10/92
  458.  
  459.  
  460.           newest file in an area.  It does NOT control which files are
  461.           included if a listing is generated.
  462.           
  463.           
  464.           The AREA Command
  465.           ----------------
  466.           
  467.           The AREA command (at least one required) is used to specify
  468.           which area(s) (forums) you want listings for.  The AREA
  469.           command requires one parameter, the area (forum) number, and
  470.           one sub-command, GEN.  It also accepts several optional
  471.           sub-commands.  All the sub-commands must be on the same line
  472.           as the AREA command.  There is no limit to the length of the
  473.           line.  All the sub-commands and their associated parameters
  474.           must be separated by one or more spaces.
  475.           
  476.           Command Format:   AREA <area #> GEN <GEN path>
  477.                               [CONDENSED <filename>] 
  478.                               [ENHANCED <filename>]
  479.                               [RAW <filename>] 
  480.                               [BULLETIN <filename>]                    
  481.                               [TITLE "<area title>"]
  482.           
  483.           The <area #> is the number of the forum to be listed.  The
  484.           main board is area 0 (zero).  You may have any number of
  485.           AREA commands in your configuration file, each on a separate
  486.           line.
  487.           
  488.           
  489.           GEN Sub-Command (AREA)
  490.           ----------------------
  491.           
  492.           Sub-Command Format:  GEN <path to AREA GEN directory>
  493.           
  494.           This is a REQUIRED sub-command that specifies the path to
  495.           the GAP GEN directory for this area.  GAP_LIST uses the GEN
  496.           path to extract subject names from the GAP DIRS file and to
  497.           determine how many subjects there are in a given area.  The
  498.           extracted subject names will be used in headers for the
  499.           subject listings.
  500.           
  501.           Example: AREA 0 GEN c:\gap\gen
  502.           
  503.           
  504.           CONDENSED Sub-Command (AREA)
  505.           ----------------------------
  506.           
  507.           Sub-Command Format:  CONDENSED <filename>
  508.           
  509.           This is an optional sub-command that indicates you want a
  510.           condensed (one line per file) listing of the associated
  511.           area.  <filename> indicates where you want the listing to
  512.           go.  <filename> may be a relative or absolute file
  513.           specification.  You must specify a filename following the
  514.           CONDENSED sub-command.
  515.           
  516.           Example:  AREA 0 GEN c:\gap\gen CONDENSED c:\gap\main.lst
  517.           
  518.  
  519.  
  520.                                      Page 8                           
  521.  
  522.           GAP_LIST v1.1                                       10/10/92
  523.  
  524.  
  525.           Files from all subjects in the specified area will be
  526.           included in the generated listings unless overridden by the
  527.           SUBJECT command.  (See below for details on the SUBJECT
  528.           command.)
  529.           
  530.           
  531.           ENHANCED Sub-Command (AREA)
  532.           ---------------------------
  533.                                                                             
  534.           Sub-Command Format:  ENHANCED <filename>
  535.           
  536.           This is an optional sub-command that indicates you want an
  537.           enhanced (complete file information) listing of the
  538.           associated area.  <filename> indicates where you want the
  539.           listing to go.  <filename> may be a relative or absolute
  540.           file specification.  You must specify a filename following
  541.           the ENHANCED sub-command.
  542.           
  543.           Example: AREA 0 GEN c:\gap\gen ENHANCED c:\gap\main.enh
  544.           
  545.           Files from all subjects in the specified area will be
  546.           included in the generated listings unless overridden by the
  547.           SUBJECT command.  (See below for details on the SUBJECT
  548.           command.)
  549.           
  550.           
  551.           RAW Sub-Command (AREA)
  552.           ----------------------
  553.           
  554.           Sub-Command Format:  RAW <filename>
  555.           
  556.           This is an optional sub-command that indicates you want a
  557.           raw listing of all the filenames for this AREA.  This is
  558.           primarily for use with protocols like HS/Link that can use
  559.           such a file to check for duplicates prior to accepting
  560.           uploads.  <filename> indicates where you want to listing to
  561.           go.  <filename> may be a relative or absolute file
  562.           specification.  You must specify a filename following the
  563.           RAW sub-command.
  564.           
  565.           Example: AREA 0 GEN c:\gap\gen RAW c:\gap\files.lst
  566.           
  567.           Files from all subjects in the specified area will be
  568.           included in the generated listings unless overridden by the
  569.           SUBJECT command.  (See below for details on the SUBJECT
  570.           command.)
  571.           
  572.           
  573.           BULLETIN Sub-Command (AREA) 
  574.           ---------------------------
  575.                                                   
  576.           Sub-Command Format:  BULLETIN <filename>
  577.           
  578.           This is an optional sub-command that indicates you want
  579.           GAP_LIST to create a summary bulletin listing the total
  580.           number of files and bytes in each SUBJECT in this AREA.  The
  581.           bulletin file is formatted to 80 columns and uses ANSI
  582.           color.  A grand total of all files in this area is printed
  583.  
  584.  
  585.                                      Page 9                           
  586.  
  587.           GAP_LIST v1.1                                       10/10/92
  588.  
  589.  
  590.           at the very bottom of the bulletin.
  591.           
  592.           Example: AREA 0 GEN c:\gap\gen BULLETIN c:\gap\gen\blt11
  593.           
  594.           
  595.           TITLE Sub-Command (AREA)
  596.           ------------------------
  597.           
  598.           Sub-Command Format:  TITLE "<area title>"
  599.           
  600.           This is an optional sub-command that specifies a title for
  601.           the area.  This title will be printed in a double-line box
  602.           at the top of the listings for this area.  If no TITLE
  603.           sub-command is used, a generic title will be generated.  The
  604.           TITLE specified MUST be enclosed in quotes ("").
  605.           
  606.           Example: AREA 0 GEN c:\gap\gen TITLE "Main Board"
  607.           
  608.           
  609.           
  610.           The SUBJECT Command
  611.           -------------------
  612.           
  613.           The SUBJECT command (registered version only) is used to
  614.           override the inclusion of all subjects in an area or to
  615.           specify a filename template for individual subject listings.
  616.           If one of more SUBJECT commands which include a subject
  617.           number follow an AREA command, ONLY the subjects specified
  618.           by these commands will be included in the listings.
  619.           
  620.           The SUBJECT command can also be used to specify a filename
  621.           template for individual subject listings.  A SUBJECT command
  622.           that does not include a subject number specifies a template
  623.           and will not override the inclusion of all subjects for a
  624.           given area.
  625.           
  626.           The SUBJECT command accepts several sub-commands.  All the
  627.           sub-commands must be on the same line as the SUBJECT
  628.           command.  There is no limit to the length of the line.  All
  629.           the sub-commands and their associated parameters must be
  630.           separated by one or more spaces.
  631.           
  632.           
  633.           Command Format:  SUBJECT [<subject #>] 
  634.                              [CONDENSED <filename>]
  635.                              [ENHANCED <filename>] 
  636.                              [RAW <filename>]
  637.           
  638.           The optional <subject #> is the number of a subject
  639.           (directory) you want included with the listing for the
  640.           associated AREA.  Specifying a <subject #> with the SUBJECT
  641.           command will override the inclusion of all subjects in the
  642.           associated area.  All SUBJECT commands are associated with
  643.           the preceding AREA command.  You may have any number of
  644.           SUBJECT commands after an AREA command.  There may be only
  645.           one SUBJECT command on a line in the configuration file.
  646.           
  647.           Example: SUBJECT 1
  648.  
  649.  
  650.                                     Page 10                           
  651.  
  652.           GAP_LIST v1.1                                       10/10/92
  653.  
  654.  
  655.           
  656.           CONDENSED Sub-Command (SUBJECT)
  657.           -------------------------------
  658.           
  659.           Sub-Command Format:  CONDENSED <filename>
  660.           
  661.           This is an optional sub-command that indicates you want a
  662.           condensed (one line per file) listing of the associated
  663.           subject.  <filename> indicates where you want the listing to
  664.           go.  <filename> may be a relative (..\main.lst) or absolute
  665.           (c:\gap\filelist\main.lst) file specification.  You must
  666.           specify a filename following the CONDENSED sub-command.
  667.           
  668.           Example:  SUBJECT 1 CONDENSED c:\gap\dir1.lst 
  669.           
  670.           This SUBJECT command will override the inclusion of all
  671.           subjects in the associated AREA.  With this type of SUBJECT
  672.           command you must include a SUBJECT command for each subject
  673.           desired.
  674.           
  675.           Example:  SUBJECT CONDENSED c:\gap\dir%03i.lst
  676.           
  677.           This SUBJECT command specifies a filename template for
  678.           individual subject listings.  It does NOT override the
  679.           inclusion of all subjects in the associated AREA.  GAP_LIST
  680.           will use the specified file path/name as a template for the
  681.           individual subject listings.
  682.           
  683.           This template is in C printf format.  (If you aren't
  684.           familiar with this format, here's a brief explanation.  The
  685.           '%' sign indicates the beginning of a substitutable portion
  686.           of the string.  The '03' indicates that the substitutable
  687.           part is 3 characters long and should be padded on the left
  688.           with leading zeros.  The 'i' indicates the substitutable
  689.           parameter, in this case the subject number, is an integer.)
  690.           You can use any pattern you want for the filename, but be
  691.           sure the resulting filename will be legal.  GAP_LIST does no
  692.           error checking on the result and you may get very strange
  693.           results if your template doesn't generate a legal filename.
  694.           
  695.           The example above, c:\gap\dir%03i.lst, will generate files
  696.           DIR001.LST, DIR002.LST, DIR003.LST, etc.  in the C:\GAP
  697.           directory.  The template dir.%03i would generate files
  698.           DIR.001, DIR.002, DIR.003, etc.
  699.           
  700.           The SUBJECT CONDENSED listing is completely independent of
  701.           the AREA CONDENSED listing.  You may generate either or both
  702.           on any given run of GAP_LIST.
  703.           
  704.           
  705.           ENHANCED Sub-Command (SUBJECT)
  706.           ------------------------------
  707.           
  708.           Sub-Command Format:  ENHANCED <filename>
  709.           
  710.           This is an optional sub-command that indicates you want an
  711.           enhanced (complete file information) listing of the
  712.           associated subject.  <filename> indicates where you want the
  713.  
  714.  
  715.                                     Page 11                           
  716.  
  717.           GAP_LIST v1.1                                       10/10/92
  718.  
  719.  
  720.           listing to go.  <filename> may be a relative or absolute
  721.           file specification.  You must specify a filename following
  722.           the ENHANCED sub-command.
  723.           
  724.           Example: SUBJECT 1 ENHANCED c:\gap\dir1.enh
  725.           
  726.           This SUBJECT command will override the inclusion of all
  727.           subjects in the associated AREA.  With this type of SUBJECT
  728.           command you must include a SUBJECT command for each subject
  729.           desired.
  730.           
  731.           Example:  SUBJECT ENHANCED c:\gap\dir%03i.enh
  732.           
  733.           This SUBJECT command specifies a filename template for
  734.           individual subject listings.  It does NOT override the
  735.           inclusion of all subjects in the associated AREA.  GAP_LIST
  736.           will use the specified file path/name as a template for the
  737.           individual subject listings.  See the SUBJECT CONDENSED
  738.           Sub-command for an explanation of the template format.
  739.           
  740.           The SUBJECT ENHANCED listing is completely independent of
  741.           the AREA ENHANCED listing (or any of the CONDENSED
  742.           listings).  You may generate either or both (or all) on any
  743.           given run of GAP_LIST.
  744.           
  745.           RAW Sub-Command (AREA)
  746.           ----------------------
  747.           
  748.           Sub-Command Format:  RAW <filename>
  749.           
  750.           This is an optional sub-command that indicates you want a
  751.           raw listing of all the filenames in this SUBJECT.  This is
  752.           primarily for use with protocols like HS/Link that can use
  753.           such a file to check for duplicates prior to accepting
  754.           uploads.  <filename> indicates where you want to listing to
  755.           go.  <filename> may be a relative or absolute file
  756.           specification.  You must specify a filename following the
  757.           RAW sub-command.
  758.           
  759.           The RAW sub-command follows the same general format as the
  760.           SUBJECT CONDENSED and SUBJECT ENHANCED sub-commands.  If the
  761.           SUBJECT command contains a subject number it will override
  762.           the inclusion of all subjects in the associated area.  If
  763.           the SUBJECT command does not include a subject number, the
  764.           RAW filename will be used as a template to generate raw
  765.           listing filenames for each subject in the associated area.
  766.           
  767.           
  768.           
  769.           
  770.           How about some real world examples?
  771.           -----------------------------------
  772.           
  773.           Let's take my GAP board as an example.  I have files in my
  774.           main board and in the Windows Forum (forum #2), the Graphics
  775.           Forum (forum #3), and the Programming Forum (forum #4).
  776.           
  777.           I want to generate condensed and enhanced listings for all
  778.  
  779.  
  780.                                     Page 12                           
  781.  
  782.           GAP_LIST v1.1                                       10/10/92
  783.  
  784.  
  785.           the subjects in the main board, the Windows forum, and the
  786.           graphics forum.  I want individual condensed listings for
  787.           each of the subject in the main board.  I want listings for
  788.           the programming forum, but only for subjects 1 and 2. I also
  789.           want to generate a raw listing of all these files for use
  790.           with the HS/Link batch upload checker.  Here's a GAP_LIST
  791.           configuration file that will do this.  (NOTE: In the
  792.           following example some of the command lines would not fit
  793.           within the margins of this document so they have been split
  794.           onto multiple lines.  This is not allowed in an actual
  795.           GAP_LIST parameter file.  The wrapped parts of the command
  796.           lines are indented and have an asterisk (*) in the first
  797.           column.)
  798.           
  799.           MAIN i:\gap\main
  800.           PRIVATE 110
  801.           SEPARATOR -
  802.           IGNORE main_lst.zip main_enh.zip win_lst.zip win_enh.zip
  803.           IGNORE grph_lst.zip grph_enh.zip prgm_lst.zip prgm_enh.zip
  804.           IGNORE dir001.zip dir002.zip dir003.zip dir004.zip
  805.           IGNORE dir005.zip dir006.zip dir007.zip dir008.zip
  806.           IGNORE dir009.zip dir010.zip dir011.zip dir012.zip
  807.           MASTER RAW c:\gap\files\files.lst
  808.           AREA 0 CONDENSED main.lst ENHANCED main.enh GEN gen 
  809.           *     TITLE "The Cookie Jar Main Board Files"
  810.           SUBJECT CONDENSED dir%03i.lst
  811.           AREA 2 CONDENSED windows.lst ENHANCED windows.enh 
  812.           *     TITLE "The Cookie Jar Windows Forum" 
  813.           *     GEN c:\gap\windows\gen
  814.           AREA 3 CONDENSED graphics.lst ENHANCED graphics.enh
  815.           *     TITLE "The Cookie Jar Graphics Forum"
  816.           *     GEN c:\gap\graphics\gen
  817.           AREA 4 CONDENSED program.lst ENHANCED program.enh
  818.           *     TITLE "The Cookie Jar Programming Forum"
  819.           *     GEN c:\gap\program\gen
  820.           SUBJECT 1
  821.           SUBJECT 2
  822.           
  823.           
  824.           Limitations
  825.           -----------
  826.           
  827.           When configured to generate the maximum number of listings,
  828.           GAP_LIST opens a lot of files at the same time.  If you
  829.           start getting "Can't open file" messages, be sure you have
  830.           your FILES= in your CONFIG.SYS set to at least 30.
  831.           (FILES=30)
  832.           
  833.           The demo version of GAP_LIST has the following limitations:
  834.           
  835.              1) Single-node operation only.  Do NOT attempt to run 
  836.                 the demo version on a multi-node system when any of
  837.                 the nodes are active!
  838.              2) No individual subject listings.
  839.              3) All listings will be generated everytime the program
  840.                 is run.  Only the registered version contains the
  841.                 ability to generate a listing only if there are new
  842.                 files in an area/subject.
  843.  
  844.  
  845.                                     Page 13                           
  846.  
  847.           GAP_LIST v1.1                                       10/10/92
  848.  
  849.  
  850.              4) Listings will be marked as having been generated by an
  851.                 unregistered copy of GAP_LIST.
  852.           
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.                                     Page 14                           
  911.